Shareware Grab Bag/Shareware Grab Bag.iso/007/ovl20.arc/OVL.DOC

Text File | 1988-03-11 | 24KB | 582 lines

                       OVL 2.0 DOCUMENTATION
                       ---------------------



LICENSE AND WARRANTY
--------------------

OVL is copyright (C) 1988 by Michael E. Devore

The copyright holder licenses you to copy and distribute OVL for
yourself and others subject to the following three restrictions:

1.  OVL must be copied and distributed only in its original,
    unmodified form.  This includes the executable,
    documentation, and all example files.

2.  No fee or other compensation can be charged for copying or
    distributing the program.  User groups and public domain
    software distributors MAY charge a handling fee for its
    distribution NOT TO EXCEED $7.00 PER COPY.  ONLY ONE COPY
    PER DISK IS ALLOWED FOR SUCH DISTRIBUTION.

3.  OVL may NOT be distributed in combination with any other
    products, software or hardware, without the express written
    permission of Michael E. Devore.

There is no warranty of any kind with OVL and the copyright
holder is not liable for any damages of any nature that may occur
due to use of this software.  By using OVL, you agree to these
terms.

It is the copyright holder's goal to fix any errors in OVL and
to allow its distribution free of charge.  The copyright holder,
however, is NOT LEGALLY OBLIGATED TO DO SO.

This document copyright (C) 1988, Michael E. Devore.  All rights
reserved.


------------------------------------------------------------------------------
------------------------------------------------------------------------------


OVL FILES
---------

Included in OVL.ARC should be the following files:

OVL.EXE             (OVL executable program)
OVL.DOC             (OVL documentation file)

MASMTEST.ASM        (MASM example files)
MASMTEST.OBJ
OV1.ASM
OV1.OBJ
OV2.ASM
OV2.OBJ
OV3.ASM
OV3.OBJ

COW.C               (Turbo C example files)
COW.OBJ
FARM.C
FARM.OBJ
HORSE.C
HORSE.OBJ
PIG.C
PIG.OBJ
PIGLET.C
PIGLET.OBJ
SHEEP.C
SHEEP.OBJ

QBNEST.BAS          (QuickBASIC 4.0 example files)
QBNEST.OBJ
BNEST1.BAS
BNEST1.OBJ
BNEST2.BAS
BNEST2.OBJ
BNEST3.BAS
BNEST3.OBJ
BNEST4.BAS
BNEST4.OBJ

QB4MOD.OBJ          (Object module required for QuickBASIC 4.0 programs)


------------------------------------------------------------------------------
------------------------------------------------------------------------------


What is OVL?
------------

OVL is an overlay manager.  But what is an overlay manager and
what good is it?  To answer that question we first need a little
background on what overlays are and why they are useful.

Overlays are portions of your program code which are loaded from
disk into memory on an as-needed basis.

Use of overlays allows an extremely large (potentially equal to
hard disk size) program to run in a much smaller amount of
memory.  Code from the program's .EXE file is brought in disk
(overlaid) only when the program needs it.  Since all overlays
share the same memory space, the memory requirements can be much
less than the total code size of the program.  Also, there is no
longer a need for the messy chaining, spawning, or exec'ing to
another .EXE file that some languages require.

There is a tradeoff for these advantages.  The tradeoff is the
time and code overhead necessary to read overlays in from disk.
If you make the decision to use overlays with your program, any
timing critical code should not be divided between overlays.
For most applications, though, the relatively small amount of
time it takes to read in an overlay is not important if
transfers to overlays are not overdone.  Constant shuttling
between overlays is an exercise guaranteed to give disappointing
results.

LINK versions 3.x from Microsoft allow creation of overlaid
versions of programs.  However, LINK only sets up the calls to
the overlays.  It doesn't generate the actual code that loads
the proper overlay from disk and passes control to it.  That's
where OVL comes in.

OVL "manages" overlays.  It loads them in from disk at the
appropriate time and jumps program execution to the overlay
code.

To use OVL, first link your program with overlays using
Microsoft's LINK.  Your LINK documentation should show you how
to do this.  If not, or you don't completely understand the LINK
documentation, study the examples in the 'USING OVL' section
later in this document.  Also, if you are using QuickBASIC 4.0,
you will need to link in the included object module QB4MOD.OBJ
as the first object file.

After you have linked a program with overlays, type OVL <program
name>.  OVL will begin execution, controlling the loading and
overlay management of your program.  If the program loaded by
OVL has command line parameters, these will be properly passed
to the loaded program.  If, for example, you had a program
containing overlays named MYPROG that used the command line
switch /B to make it beep, you could type OVL MYPROG /B and it
would work correctly.  Note that typing the .EXE extension of a
program is optional.


------------------------------------------------------------------------------
------------------------------------------------------------------------------


OVL SPECIFICATIONS AND REQUIREMENTS
-----------------------------------

OVL requires an IBM PC or PS/2 microcomputer or close compatible
that runs MS-DOS or PC-DOS 2.1 or later.

OVL requires 16K memory when in use.  This is in addition to
whatever memory your program requires.

OVL has only been tested with MASM, Turbo C, and QuickBASIC 4.0.
Use of OVL with QuickBASIC 4.0 requires linking in an additional
object module (QB4MOD.OBJ) as the first object file and
compiling using the /o option of BC.EXE.  It is probable, but
not known for fact, that OVL will work with ALL languages that
compile to Microsoft LINKable object modules.  Microsoft or
other languages may --  QuickBASIC 4.0 does -- require the
presence of an additional object module to operate correctly.
The object files created by versions of QuickBASIC earlier than
4.0 abort with an error if an link is attempted with overlays.
Therefore, OVL will not work with versions of QuickBASIC earlier
than 4.0.

OVL requires at least one overlay in your program.  It will
abort with an "Invalid overlay information." error if none
exist.

OVL has a current limit of eight overlays.  More than eight
overlays will cause OVL to abort with a "Too many overlays."
error.  PROVL, the enhanced version of OVL, has a limit of 63
overlays -- LINK's maximum.

OVL support calls from one overlay to another.  The depth to
which overlays can be nested cannot exceed four levels.  If an
attempt is made to nest deeper than four overlays, OVL will
abort with a "Overlays nested deeper than 4 levels." error.
PROVL supports a nesting depth of 32 levels.

OVL requires use of the Microsoft LINK default overlay interrupt
63 (3fh).  Do not use the /o option of LINK to change the
overlay manager interrupt.  PROVL supports changing the default
overlay manager interrupt via the /o option of LINK.

OVL may not work with other non-default LINK parameters.  For
instance, the /E option will not work with OVL.  There may be
others.

OVL should not be used to execute memory resident programs.

OVL fully supports and uses the PATH= environment variable when
searching for the program to execute.  However, after OVL has
located the program, the program should not be moved from the
drive and directory where it was found.  Otherwise, OVL will
abort with a "File not found." error when it attempts to load an
overlay from disk.

This version of OVL WILL work with overlay .EXE files that have
any LINK-allowed number of relocation entries (up 32K).  If you
don't know what a relocation entry is, don't worry about it.
OVL will work just the same.


------------------------------------------------------------------------------
------------------------------------------------------------------------------


USING OVL
---------

To demonstrate how to use LINK to set up overlays, there are
three sets of sample programs included in the OVL files.  One
set is written using MASM 5.0, another using Turbo C 1.5, and
the third using QuickBASIC 4.0.  Both source and .obj files have
been included.

As stated in the LINK documentation, you MUST compile under a
large code model for programs to work correctly with overlays.
For MASM 5.0, this means you must compile using .MODEL MEDIUM
(far-code, near-data), .MODEL LARGE (far-code, far-data), or
.MODEL HUGE (far-code, far-data).  If you are using an earlier
version of MASM, make sure that PUBLIC procedures are declared
FAR.  For Turbo C version 1.0 and 1.5, compile your files under
the medium, large, or huge model.  No compile model options are
necessary for QuickBASIC, although you must use the /o option of
BC.EXE for your program to work correctly.

The first example will use the assembly language .ASM files
written using MASM 5.0.  Although the .MODEL LARGE is used for
these example files, .MODEL MEDIUM and .MODEL HUGE should work
in exactly the same fashion for overlaying purposes.

Link together the ASM .obj files, enclosing in parentheses the
modules you want to be overlays.  Make sure that you use at
least one overlay or OVL will not work with the file.  If, for
instance you link in this manner:

     link masmtest+(ov1+ov2)+(ov3);

a main .EXE file called MASMTEST.EXE will be created.  This
MASMTEST.EXE file will contain the root .EXE file MASMTEST
comprised of the code of the MASMTEST object module and will
also contain two overlay files.  One overlay file will contain
the code of the OV1 and OV2 modules, the other will contain the
code of OV3.

To run the MASMTEST.EXE FILE created from the link, type OVL
MASMTEST.  You may haved noted from the OV1.ASM file that the
OV1 module calls a routine in the root module.  Since the root
is always in memory, the call is coded normally by LINK and no
special overlay instructions are required.  This is an important
point to remember about overlays:  THERE IS NO SPEED OR CODE
PENALTY INVOLVED IN CALLING ROUTINES FROM A LOADED OVERLAY TO
THE ROOT CODE OR FROM ONE OBJECT MODULE TO ANOTHER WITHIN THE
SAME OVERLAY.

The amount of memory required to load the MASMTEST.EXE file you
created, or any file created by LINK using overlays, is equal to
the size of the root file plus the size of the largest overlay
file plus any program overhead and dynamic memory allocations
made by the program plus 16K for OVL.  Obviously, there is no
advantage to only using one overlay in a program since space
must be allocated for it in memory during program execution
anyway.  There is only the disadvantage of the overlay overhead.

Another example of linking using overlays would be:

     link masmtest+(ov1)+(ov2)+ov3;

Here there will be two overlay files containing the code of,
respectively, OV1 and OV2, and a root file containing the
MASMTEST and OV3 code.

The only overlay combination not allowed by OVL is one where the
MASMTEST object module is linked as an overlay.  Since MASMTEST
contains the start up code it must be in memory from the very
beginning.

The second set of files are examples using Turbo C.  To use
them, you need to have the Turbo C compiler, since 'C' requires
startup and library modules specific to the compiler.  OVL is
put a little more to the test here because the code is larger,
parameters are passed to the overlays and a command line
argument can be passed.  Further, in one module, PIG.C, overlays
can be nested if the 'piglet' function that is called from it is
located in a different overlay module.

To create FARM.EXE with an overlay file containing the code of
'horse' and 'piglet' and an overlay file containing the code of
'cow', 'pig', and 'sheep' and a root containing the code of
'farm' and the start up code of 'c0m', you would link like this,
assuming that the code has been compiled using the medium model:

     link c0m+farm+(horse+piglet)+(cow+pig+sheep),farm,nul,
     emu+mathm+cm;

After you link the program, try running it by typing "OVL FARM"
and "OVL FARM MACDONALD" to see the command line parameter in
use.  All of the modules can be put in an overlay except for
'c0m' which contains the start up code.  Remember, you must use
Microsoft's LINK when linking this or any other Turbo C program
for use with OVL.  The copy of TLINK included with Turbo C does
not support overlays.

The final set of examples are QuickBASIC 4.0 files.  There is an
extra step involved in using QuickBASIC 4.0 programs with OVL.
An extra object module called QB4MOD.OBJ must be linked in as
the first object file during the link process.  So, to create a
program called QBNEST.EXE with a root of QB4MOD and QBNEST, an
overlay containing BNEST1 and BNEST2, an overlay containing
BNEST4, and an overlay containing BNEST3, you would link in
this fashion:

     link qb4mod+qbnest+(bnest1+bnest2)+(bnest4)+(bnest3),qbnest;

Because of the way QB4MOD is coded, it must be in the root with
the main program.  In these example files, neither QB4MOD nor
QBNEST can be in an overlay.

To use your own QuickBASIC 4.0 programs with overlays you should
compile the files using BC.EXE.  Overlays will not work with the
runtime file BRUN40.EXE, so the /o option must be used to
compile QuickBASIC 4.0 programs.

Feel free to try any permutation of overlays allowed by these
examples.  OVL should work with any of them, as long as you stay
within the restrictions already outlined.  It is especially
important to remember not to put the initial entry code in an
overlay.  The start up code must be in memory when the program
is first loaded, i.e. in the root code.

You may have noticed that these example files are all small
enough to fit into memory without overlays.  How do you really
know that OVL is bringing the overlays in as needed instead of
sneaking everything in at once?

First, you can try running a file linked with overlays without
OVL.  If you do this your computer will probably lock up and
need to be turned off or reset before it can be used again.
This is because your program is using interrupt 63 which OVL
hasn't initialized to point to code that manages the overlays.
So, your program tries to transfer control to whatever random
address may be at interrupt 63.

The second test you can do is transfer OVL.EXE and the example
.EXE file to a floppy and disable any disk caching.  Now run OVL
off of the floppy drive.  You should see the floppy disk drive
light come on during execution of the example program as
overlays are loaded from disk.  For maximum effect, you may want
to link the example program using as many overlays as possible.


------------------------------------------------------------------------------
------------------------------------------------------------------------------


PROVL -- An Enhanced Version of OVL
-----------------------------------

If you wish to sell a program that uses OVL to operate, or if
you just want a more powerful version of OVL, an enhanced
version of OVL called PROVL can be purchased for $45.  PROVL
works with any overlay interrupt specified by the /o option of
LINK, allows up to 63 overlays (LINK's maximum), and increases
the depth that overlays can be nested to 32 levels.  PROVL also
dispenses with the runtime copyright notice.  This does not
imply that PROVL is not copyrighted.  A potentially distracting
message is simply not displayed.  No royalties will be charged
for use of PROVL.  This means that you need only purchase a
single version of PROVL for use with your program no matter how
many copies of your program you distribute.  Purchase of PROVL
also entitles the purchaser to telephone support.  All calls
will be at the purchaser's expense.

Note that purchase of PROVL is MANDATORY if you wish to use a
version of OVL for distribution with a commercial or shareware
program.  PROVL is the only version of the overlay manager
permitted for such applications.

To purchase PROVL, send $45.00 by check or money order with your
shipping address to:

    Michael E. Devore
    Devore Software & Consulting
    403 West Charles
    Champaign, IL  61820

Please state your preference for either 5 1/4 or 3 1/2 inch
diskettes.

All information contained herein, including the cost of PROVL,
is subject to change without notice.

PROVL is copyright (C) 1988 by Michael E. Devore


------------------------------------------------------------------------------
------------------------------------------------------------------------------


If OVL Doesn't Work Properly
----------------------------

First, make sure that you have compiled the language under a
large code model, if applicable.  OVL will not work under a
small code model.  Also, you should use a relatively recent
version of LINK when linking overlays for OVL.  OVL was tested
with LINK versions 3.06, 3.60 and 3.61.  2.x versions of LINK
will not work.  The copyright notice of LINK must say Overlay
Linker.  Turbo C's TLINK or other proprietary linkers will not
work with OVL; you must use Microsoft's LINK.

QuickBASIC 4.0 users should check to make sure that they are
linking in QB4MOD.OBJ as the first object file during link.
Make sure that neither QB4MOD nor the main program is in an
overlay.  Because of the highly specific nature of the
QB4MOD.OBJ file, OVL may only work with version 4.0 of
QuickBASIC and not later versions.  If this proves to be the
case, contact me about an updated QB4MOD.OBJ file to allow use
of OVL with later versions.

If you are sure that you are compiling and linking properly, try
to make sure that the error is not in your program.  If memory
size allows, compile your program without overlays and test it.
If the size of your program is too large for it all of it to fit
in memory, try to compile only the code that is giving you
problems and see if it works correctly without overlays.

If your program still fails after you have eliminated all
suspects except for OVL, please contact me so I can fix the
problem as soon as possible.  However, I will need to know the
circumstances.  What error message, if any, does OVL print?
What version and options of LINK were used?  What language was
the program written in?  If possible I would like to have a copy
of the program that causes OVL to crash, executable copy at the
least.

If the error is in OVL and you are the first person to find the
error, I will send you a free corrected version as soon as it is
available.  The corrected version will either be sent by e-mail
if possible, or regular USPS mail if not.  If you are not the
first person to find the error and cannot wait for the corrected
version to reach general distribution channels, you may send
$5.00 to cover shipping and handling for the latest version to
the address below.

If you subscribe to either the CompuServe Information Service,
or the GEnie Information Service, you can e-mail me at the
appropriate e-mail address below.  I check in to both services
at least once a week, usually more frequently.  Your e-mail will
be acknowledged as soon as I receive it.

If you do not subscribe to either CompuServe or GEnie you should
contact me through USPS mail at the address below:

MAILING ADDRESS:
     Michael E. Devore
     Devore Software & Consulting
     403 W. Charles
     Champaign, IL  61820

E-MAIL ADDRESSES:
     CompuServe     71540,62
     GEnie          MDEVORE


------------------------------------------------------------------------------
------------------------------------------------------------------------------


OVERLAY TECHNICAL DOCUMENTATION
-------------------------------

It is not necessary to read or understand this part of the OVL
documentation to use OVL.  This technical documentation is
included for those who wish to know more information about how
overlay calls are set up by LINK.

When you link a program with overlays, LINK sets up calls to
code in the overlays in a special way.  All of these calls are
replaced with an interrupt.  By LINK default the interrupt is 63
or 3f hexadecimal, although the interrupt can be changed using
the /o or /overlayinterrupt LINK option.  Please note that
changing the overlay interrupt in this fashion is not supported
by OVL, and OVL will not work with a program linked using the
non-default overlay interrupt.  PROVL, the enhanced version of
OVL, does support changing the interrupt via the /o option of
LINK.

Immediately following the interrupt inserted by LINK are three
bytes of data.  The first byte is used by the overlay manager as
an offset into an table found at the end of the root
.EXE code that determines which overlay should be loaded into
memory.  The second two bytes give the value that the
Instruction Pointer (IP) should have when a jump to the overlay
code is executed.  When the overlay manager is called by the
interrupt, it needs to adjust the return address to point past
these three bytes.

The remaining information that the overlay manager needs can be
found at the end of the root .EXE file.  Note that an .EXE
program with overlays appends the overlay .EXE files to the root
.EXE file.  Each overlay file has its own header that matches
the standard .EXE header, including items in the relocation
table that need to be have fixups performed on them.  The
information that the root .EXE has is as follows:

     1 word containing the count of all .obj modules used to
     create the .EXE file (total of root plus all overlay
     modules).

     1 word containing the total .EXE files in the main .EXE
     file.  This will equal the number of overlay files plus one
     for the root.

     1 zero word.

     A table with entries for each overlay that, when added to
     the root program load segment, provide the value the Code
     Segment (CS) should have when a jump to the overlay code is
     executed.

     1 zero word.

     A table that uses the first byte following the interrupt in
     the calling code for an offset.  The entries in the table
     determine which overlay has the necessary code and should
     be loaded in memory, if it isn't loaded already.

     Variable number of zero bytes.

     The name of the main .EXE file that has all of the overlay
     files contained in it.

     Variable number of zero bytes.

     The interrupt used by the overlay manager.


------------------------------------------------------------------------------
------------------------------------------------------------------------------


COMMENTS AND SUGGESTIONS
------------------------

If you have an idea for an improvement to OVL, a comment or
question about OVL, or even a complaint about OVL, please send
it to either my USPS mailing address or one of the e-mail
addresses below.  I am receptive to new ideas and constructive
criticism.  I would also be interested in what other languages
OVL works with, e.g. Turbo BASIC, Turbo Prolog, or another 'C'
compiler.

OVL began as a grass-roots solution to the problem of a low-cost
overlay manager.  I hope to maintain that approach and never
take on the arrogant traits exhibited by some software
developers and mega-corporations.  With your help, I plan to
keep OVL a viable, useful, low-cost alternative to overpriced
software.

     Michael E. Devore
     Devore Software & Consulting
     403 W. Charles
     Champaign, IL  61820

     CompuServe      71540,62
     GEnie           MDEVORE